STMH v1.2b Beta release 14/1/95 Development by Stephen K Mulrine Additions by Graeme Mullin Bug reports and comments to stmh@moroder.demon.co.uk Based (loosely) on the Rand MH Message Handling System. Requirements ------------ Any Atari ST, TT or Falcon Hard disk with at least .5MB free Demon NOS software Text editor (e.g. Gnome, as supplied with Demon's NOS package) First-time Installation ----------------------- 1. Print this file! You won't be able to use STMH without a list of commands. 2. Copy all the .ttp and .bat files into the same directory as the NOS software. 3. Double-click on "demon.tos" and choose option F (at time of writing) for "Command Shell". 4. Enter "stmhinst". This will create a directory called "stmh", your first message folder ("+outgoing"), and a configuration file called "stmh.rc" using the settings from your "mailer.rc" file. (You may then wish to examine or edit this file, e.g. "gnome stmh\stmh.rc".) 5. Enter "inc" to extract messages from your mailbox. Upgrading from v1.1 ------------------- 1. Copy all the .ttp and .bat files into the same directory as the NOS software. 2. Double-click on "demon.tos" and choose option F (at time of writing) for "Command Shell". 3. Edit your configuration file (e.g. "gnome stmh\stmh.rc") and change the setting for the "news" variable from "mail2news@news.demon.co.uk" to "mail2news@peernews.demon.co.uk". Concepts -------- STMH uses folders, within which messages are stored. Folder names are prefixed by a "+". Each message within a folder has a number. Messages can be moved from folder to folder. And, because folders are independent of one another, two messages in different folders can have the same number. There are three "special" folders. "+inbox" is normally used to hold new (incoming) messages, "+outgoing" holds all your replies until you send them, and "+sent" optionally holds a copy of all the messages you send. When you forward or reply to a message, or compose a new one, you create a new message in the "+outgoing" folder. You don't have to send it straight away - you can have several messages in "+outgoing" at a time, and only send a particular message when you've finished working on it. Just as STMH breaks your mailbox up into separate messages, STMH itself is broken up into several different programs. (Most other mailers consist of one program with all the necessary functions built in.) The idea behind this is that you can intersperse mailer commands with other functions, e.g. edit a program, reply to somebody's mail, compile the program.. Programs -------- stmhinst: set up STMH according to existing "mailer" configuration stmh: list STMH functions (basically shows this list) inc: read messages from mailbox into folder scan: give one-line summaries of messages in folder refile: move a message from one folder to another rmm: remove a message folders: list existing folders show: display a message next: display next message prev: display previous message comp: compose a new message repl: reply to a message forw: forward a message pending: give one-line summaries of messages waiting to be sent send: send a message post: post a message as a news article compact: renumber messages in a folder, starting at 1 whatnow: simple front end used by comp, repl and forw All the programs, with the exception of stmhinst and stmh, can be run with a "-help" flag for a full description of command-line arguments without actually performing that function - "rmm -help" is perfectly safe. Related files ------------- stmh.rc: configuration file signatur: signature file aliases: list of aliases If the STMH environment variable is undefined, STMH looks for all these files in the directory "$NOS_ROOT\stmh". Environment variables --------------------- NOS_ROOT: NOS base directory; also used by NOS and SNEWS STMH: STMH base directory (default is $NOS_ROOT\stmh) STMHCFG: configuration file (default is $STMH\stmh.rc) STMHMBX: name of mailbox (default is based on user name) USERNAME: user name (alternatively USER) FULLNAME: full name (alternatively NAME) ORGANIZATION: name of organisation (alternatively ORGANISATION) HOSTNAME: host name (alternatively HOST) DOMAINNAME: domain name (alternatively DOMAIN) TIMEZONE: time zone (alternatively TZ). Default is +0000 EDITOR: name of editor to use (default is "vi") Configuration file settings (default values shown where appropriate) -------------------------------------------------------------------- user: user name mailbox: name of mailbox (only needed if different from user name) name: full name host: host name domain: domain name (not needed if host name includes .demon.co.uk) editor: name of editor to use (if not set, default to "vi") org: name of organisation (only used for news articles) timezone: valid RFC-822 time zone (if not set, defaults to +0000) archive: save a copy of sent messages in folder "+sent"? (y/N) us_date: show "inc", "scan" and "pending" dates in US format? (y/N) backup: keep a backup (.bkp) of all deleted/sent messages? (Y/n) update: should "inc" make "+inbox" the current folder? (Y/n) news: email address of mail-to-news gateway gateway: mail gateway for all mail to be relayed through reply_quote: quote character to use when replying [>] forward_quote: quote character to use when forwarding [>] Note that where an environment variable and a configuration file setting have the same meaning, the environment variable will always take precedence. Examples -------- inc reads mail into folder "+inbox" inc +new reads mail into folder "+new" inc root reads mail into folder "+inbox" from root's mailbox scan summarises messages in current folder scan +inbox summarises messages in folder "+inbox", also makes "+inbox" the current folder refile +jim moves the current message into folder "+jim" refile 4 +jim moves message 4 in the current folder into folder "+jim" refile +a +b moves the current message from folder "+a" into folder "+b" rmm removes the current message rmm 5 removes message 5 in the current folder rmm 5 +jim removes message 5 in folder "+jim" folders lists existing folders - current folder denoted by "*" show display current message show 6 display message 6 in the current folder (and set current message to be 6) show 6 +jim display message 6 in folder "+jim" show -full display current message with full headers show -file f1 save current message to file "f1" next display message after current message (and set current message to be this one) next +jim display next message in folder "+jim" prev display message before current message (and set current message to be this one) prev +jim display previous message in folder "+jim" comp compose a new message comp 7 edit message 7 in folder "+outgoing" comp -file x1 compose a new message, incorporating file "x1" repl reply to current message repl 8 reply to message 8 in current folder repl 8 +jim reply to message 8 in folder "+jim" repl -full reply to current message, quoting original headers forw forward current message forw 9 forward message 9 in current folder forw 9 +jim forward message 9 in folder "+jim" forw -full forward current message, quoting original headers pending summarise messages in "+outgoing" folder pending -sent summarise messages in "+sent" folder (if "archive" is set in configuration file) send move current message from "+outgoing" folder to outgoing mail queue send -archive as above, but save a copy in folder "+sent" (also happens if "archive" is set in configuration file) send 10 move message 10 from "+outgoing" folder to outgoing mail queue post move current message from "+outgoing" folder to outgoing mail queue, to be sent to mail-to-news gateway post -archive as above, but save a copy in folder "+sent" (also happens if "archive" is set in configuration file) post 11 move message 10 from "+outgoing" folder to outgoing mail queue, to be sent to mail-to-news gateway whatnow prompt for what to do with current message in "+outgoing" folder whatnow 12 prompt for what to do with message 12 in "+outgoing" folder compact renumber messages in current folder, starting at 1 Signature File -------------- A file called "signatur" in the STMH base directory is appended to every message being composed, replied-to or forwarded. Alias File ---------- If it exists, a file called "aliases" in the STMH base directory is consulted every time a message is sent. If the recipient's name is listed in the alias file, it will be replaced by the corresponding address. An example "aliases": bill1 Bill Gates bill2 Bill Clinton Any (non-zero) amount of white space between the alias and its translation will suffice. Note that aliases are not recursively expanded. Composing A Message ------------------- To create a message to send to somebody, enter "comp". This will put you into your chosen editor with a blank message template to work on (and your "signatur" file appended, if you have one). The message template consists of the lines "To: " and "Subject: ", followed by a blank line. Fill in the recipient's address and the subject line, and then enter your message, making sure to leave the blank line intact. (A blank line is what separates the header - subject, recipient, etc. - from your message.) If you wish to post your message as a news article, change the "To: " line to "Newsgroups: " and add the appropriate newsgroup name(s), comma-separated if there are more than one. (Note that this is not a terribly elegant way of posting news - on the whole, you'd be better off using SNEWS.) Important Notes --------------- You can't use STMH in conjunction with any other mailer as it deletes your mailbox when you "inc" messages from it, although you can certainly run "inc" on a mailbox you have read messages in using Mailer. If you "quit" instead of sending a message you've been composing, the draft will be left in "+outgoing". (You can check this out with "pending".) Make sure your ST has a proper date set before you "send" a message (it gets date-stamped at that point). Advanced users can quite safely drag the whole "stmh" directory structure and programs out of the NOS directory if they wish, as long as they set an STMH environment variable to point to the new base directory and put the programs somewhere in their PATH. The STMH variable takes precedence over NOS_ROOT for this very reason. As provided, "backup" is set so that any messages deleted (by using "inc", "post", "refile", "rmm" or "send") will be given the extension ".bak" in case of disaster. If STMH seems to get a bit slower with time, this is probably caused by large gaps in your folders (for example, if "+jim" contains two messages numbered 1 and 100, "scan +jim" will take a while to run). Use "compact" to renumber the messages. If you delete message 4 in folder "+jim" by mistake, go into the directory stmh\jim and rename "4.bak" to "4". If this was the last message, you'll also need to edit the "context" file and change the number beside "last=" to 4. You may also need to do this if you manually copy messages into a folder. Don't try to run "inc" on files which aren't proper mailboxes (i.e. don't have "From [whoever]" as their first line) as it will skip everything until it finds the start of a valid message. After post'ing or send'ing a message, a copy will be stored in the "+sent" folder. Turn this off by changing "archive=yes" to "archive=no" in the configuration file. Remember to use "rmm +sent" or "rmm +outgoing" to get rid of messages in those folders. "rmm" on its own will delete the current message in the current folder. "+sent" and "+outgoing" should never be the current folder ("pending" is provided instead of "scan +outgoing", because "scan" picks up on the "From:" address which will be yourself for every message in "+sent" and "+outgoing"). You can't do "repl 1 -noedit -exit", followed by "comp 1", and expect to be editing the message you just created a pending reply to, because the message won't necessarily have the same number in the "+outgoing" folder. I keep finding myself about to do this. (A future version of STMH will allow you to "comp cur" to edit the current message in "+outgoing".) When replying to a message, the "Reply-To:" address of that message takes precedence over the "From:" address, in accordance with RFC-822. If you don't set a "gateway" in the configuration file for all your non- local email to be relayed through, it will be sent directly to the appropriate host. Setting a gateway is equivalent to having "smtp wait 0" in your "startup.nos" file. The installation procedure sets up Demon's "post" machine as your gateway - this is my own preference. If the TIMEZONE environment variable appears to be in Unix format, e.g. "GMT-1BST", a legitimate RFC-822 timezone will be extracted from it. If this fails, the configuration file setting will be used instead (or, if there is none, the default value). If you find text goes all over the screen (i.e. all the programs display linefeeds without carriage returns), take the letter 'b' out of your UNIXMODE environment variable. If anything goes terribly, terribly wrong and you can't access your mail at all, I should be able to help if you post to the demon.ip.support.atari newsgroup. Normal Usage ------------ inc show rmm next repl (followed by "send") refile +joe Advanced Usage -------------- inc show -file b:\joe\94-07-25.joe repl -noedit -exit rmm next repl -noedit -exit rmm pending comp 1 (followed by "quit") [..time passes..] comp 1 (followed by "send") Bugs ---- Folder names can only have eight letters. Take it up with Atari. Bad things may happen if there are more than 1024 messages in a folder. Particularly, if you delete message 1023 then it may "lose" messages 1024 upwards. Or maybe the numbers are 1024 and 1025 respectively - I haven't had the patience to test this. Edit the "context" file to fix this if it happens, and don't have so many messages in the same folder in future. (Of course, the operating system will have choked on the number of files in one directory long ago, so you can safely ignore this bit.) "pending" shows the time a message in "+outgoing" was last edited, and not the time it was created (which would make more sense). The support for alternative mailbox formats hasn't been tested properly and isn't relevant to use in a Demon context, so I haven't documented it. "whatnow" exits even if "send" or "post" returns an error. For "show", "next" and "prev", flags ">" and ">>" have been provided as synonyms for "-noapp -file" and "-file" respectively, for shells which don't support redirection properly. However, ">>" seems to work with Gulam but not Tomshell, for reasons yet to be established. Header fields aren't validated yet (hence the need to leave a blank line between header and message). "folders" doesn't work under MiNT/tcsh, and "pending" shows a date of "00/00". Hacks ----- A separate file is used for each message (with default extension ".stt") giving its status ("scan" displays "-" for "already viewed", "+" for "replied-to"). This is for speed. I don't fancy reading a message header in, writing it out, writing out "Status: R" or whatever, and then writing out the whole message. Improvements since v1.0 ----------------------- Changes have been made to allow easy integration with the Demon software. Address parsing has been significantly improved. "refile" now allows you to specify two folders. Specifying multiple messages now produces an error (previously, "show 4 5" would display message 5). Improvements since v1.1 ----------------------- Signature file is now appended correctly. Messages now display correctly under MiNT/tcsh. Unix-style TIMEZONE environment variables are now converted. Future developments ------------------- Add multiple recipients. Add Cc: and Bcc:. Maybe re-implement forms (present in v1.0, dropped in v1.1). Take care of all RFC-822 header fields. See if I can do anything about the "pending" and MiNT/tcsh bugs. Implement ranges (e.g. "refile 1-4 +jim", "rmm all"). Add more MH functions (now that I have the manual pages courtesy of Graeme). Possibly consider some function for undeleting rmm'ed messages ("unrmm"?).